The vinyl npm package is a virtual file format used in Node.js streams. It is commonly used in build systems like Gulp to represent files, allowing for easy manipulation and transformation of file contents and metadata.
Creating a Vinyl File
This feature allows you to create a new Vinyl file object. The code sample demonstrates how to create a Vinyl file with a specified current working directory, base path, file path, and contents.
const Vinyl = require('vinyl');
const file = new Vinyl({
cwd: "/",
base: "/test/",
path: "/test/file.js",
contents: Buffer.from("console.log('Hello, world!');")
});
console.log(file);Reading File Contents
This feature allows you to read the contents of a Vinyl file. The code sample demonstrates how to create a Vinyl file and then read its contents as a string.
const Vinyl = require('vinyl');
const file = new Vinyl({
cwd: "/",
base: "/test/",
path: "/test/file.js",
contents: Buffer.from("console.log('Hello, world!');")
});
console.log(file.contents.toString());Checking File Properties
This feature allows you to check various properties of a Vinyl file, such as whether its contents are a buffer, a stream, or null. The code sample demonstrates how to create a Vinyl file and check these properties.
const Vinyl = require('vinyl');
const file = new Vinyl({
cwd: "/",
base: "/test/",
path: "/test/file.js",
contents: Buffer.from("console.log('Hello, world!');")
});
console.log(file.isBuffer());
console.log(file.isStream());
console.log(file.isNull());Gulp is a toolkit for automating painful or time-consuming tasks in your development workflow. It uses Vinyl as its file format, but provides a higher-level API for defining tasks and managing file streams. Compared to Vinyl, Gulp offers more built-in functionality for task automation.
Through2 is a small wrapper around Node.js streams2 Transform to avoid explicit subclassing noise. It is often used in conjunction with Vinyl to create transform streams that can manipulate file contents. While Through2 does not provide a file format like Vinyl, it complements Vinyl by offering a simple way to create transform streams.
Vinyl-fs is a file system adapter for Vinyl. It provides methods to read from the file system and write to it, using Vinyl file objects. Compared to Vinyl, vinyl-fs extends its functionality by integrating with the file system, making it easier to read and write files as Vinyl objects.
Virtual file format.
Vinyl is a very simple metadata object that describes a file. When you think of a file, two attributes come to mind: path and contents. These are the main attributes on a Vinyl object. A file does not necessarily represent something on your computer’s file system. You have files on S3, FTP, Dropbox, Box, CloudThingly.io and other services. Vinyl can be used to describe files from all of these sources.
While Vinyl provides a clean way to describe a file, we also need a way to access these files. Each file source needs what I call a "Vinyl adapter". A Vinyl adapter simply exposes a src(globs) and a dest(folder) method. Each return a stream. The src stream produces Vinyl objects, and the dest stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as the symlink method vinyl-fs provides.
var Vinyl = require('vinyl');
var jsFile = new Vinyl({
cwd: '/',
base: '/test/',
path: '/test/file.js',
contents: Buffer.from('var x = 123')
});
new Vinyl([options])The constructor is used to create a new instance of Vinyl. Each instance represents a separate file, directory or symlink.
All internally managed paths (cwd, base, path, history) are normalized and have trailing separators removed. See Normalization and concatenation for more information.
Options may be passed upon instantiation to create a file with specific properties.
optionsOptions are not mutated by the constructor.
options.cwdThe current working directory of the file.
Type: String
Default: process.cwd()
options.baseUsed for calculating the relative property. This is typically where a glob starts.
Type: String
Default: options.cwd
options.pathThe full path to the file.
Type: String
Default: undefined
options.historyStores the path history. If options.path and options.history are both passed, options.path is appended to options.history. All options.history paths are normalized by the file.path setter.
Type: Array
Default: [] (or [options.path] if options.path is passed)
options.statThe result of an fs.stat call. This is how you mark the file as a directory or symbolic link. See isDirectory(), isSymbolic() and fs.Stats for more information.
Type: fs.Stats
Default: undefined
options.contentsThe contents of the file. If options.contents is a ReadableStream, it is wrapped in a cloneable-readable stream.
Type: ReadableStream, Buffer, or null
Default: null
options.{custom}Any other option properties will be directly assigned to the new Vinyl object.
var Vinyl = require('vinyl');
var file = new Vinyl({ foo: 'bar' });
file.foo === 'bar'; // true
Each Vinyl object will have instance methods. Every method will be available but may return differently based on what properties were set upon instantiation or modified since.
file.isBuffer()Returns true if the file contents are a Buffer, otherwise false.
file.isStream()Returns true if the file contents are a Stream, otherwise false.
file.isNull()Returns true if the file contents are null, otherwise false.
file.isDirectory()Returns true if the file represents a directory, otherwise false.
A file is considered a directory when:
file.isNull() is truefile.stat is an objectfile.stat.isDirectory() returns trueWhen constructing a Vinyl object, pass in a valid fs.Stats object via options.stat. If you are mocking the fs.Stats object, you may need to stub the isDirectory() method.
file.isSymbolic()Returns true if the file represents a symbolic link, otherwise false.
A file is considered symbolic when:
file.isNull() is truefile.stat is an objectfile.stat.isSymbolicLink() returns trueWhen constructing a Vinyl object, pass in a valid fs.Stats object via options.stat. If you are mocking the fs.Stats object, you may need to stub the isSymbolicLink() method.
file.clone([options])Returns a new Vinyl object with all attributes cloned.
By default custom attributes are cloned deeply.
If options or options.deep is false, custom attributes will not be cloned deeply.
If file.contents is a Buffer and options.contents is false, the Buffer reference will be reused instead of copied.
file.inspect()Returns a formatted-string interpretation of the Vinyl object. Automatically called by node's console.log.
Each Vinyl object will have instance properties. Some may be unavailable based on what properties were set upon instantiation or modified since.
file.contentsGets and sets the contents of the file. If set to a ReadableStream, it is wrapped in a cloneable-readable stream.
Throws when set to any value other than a ReadableStream, a Buffer or null.
Type: ReadableStream, Buffer, or null
file.cwdGets and sets current working directory. Will always be normalized and have trailing separators removed.
Throws when set to any value other than non-empty strings.
Type: String
file.baseGets and sets base directory. Used for relative pathing (typically where a glob starts).
When null or undefined, it simply proxies the file.cwd property. Will always be normalized and have trailing separators removed.
Throws when set to any value other than non-empty strings or null/undefined.
Type: String
file.pathGets and sets the absolute pathname string or undefined. Setting to a different value appends the new path to file.history. If set to the same value as the current path, it is ignored. All new values are normalized and have trailing separators removed.
Throws when set to any value other than a string.
Type: String
file.historyArray of file.path values the Vinyl object has had, from file.history[0] (original) through file.history[file.history.length - 1] (current). file.history and its elements should normally be treated as read-only and only altered indirectly by setting file.path.
Type: Array
file.relativeGets the result of path.relative(file.base, file.path).
Throws when set or when file.path is not set.
Type: String
Example:
var file = new File({
cwd: '/',
base: '/test/',
path: '/test/file.js'
});
console.log(file.relative); // file.js
file.dirnameGets and sets the dirname of file.path. Will always be normalized and have trailing separators removed.
Throws when file.path is not set.
Type: String
Example:
var file = new File({
cwd: '/',
base: '/test/',
path: '/test/file.js'
});
console.log(file.dirname); // /test
file.dirname = '/specs';
console.log(file.dirname); // /specs
console.log(file.path); // /specs/file.js
file.basenameGets and sets the basename of file.path.
Throws when file.path is not set.
Type: String
Example:
var file = new File({
cwd: '/',
base: '/test/',
path: '/test/file.js'
});
console.log(file.basename); // file.js
file.basename = 'file.txt';
console.log(file.basename); // file.txt
console.log(file.path); // /test/file.txt
file.stemGets and sets stem (filename without suffix) of file.path.
Throws when file.path is not set.
Type: String
Example:
var file = new File({
cwd: '/',
base: '/test/',
path: '/test/file.js'
});
console.log(file.stem); // file
file.stem = 'foo';
console.log(file.stem); // foo
console.log(file.path); // /test/foo.js
file.extnameGets and sets extname of file.path.
Throws when file.path is not set.
Type: String
Example:
var file = new File({
cwd: '/',
base: '/test/',
path: '/test/file.js'
});
console.log(file.extname); // .js
file.extname = '.txt';
console.log(file.extname); // .txt
console.log(file.path); // /test/file.txt
file.symlinkGets and sets the path where the file points to if it's a symbolic link. Will always be normalized and have trailing separators removed.
Throws when set to any value other than a string.
Type: String
Vinyl.isVinyl(file)Static method used for checking if an object is a Vinyl file. Use this method instead of instanceof.
Takes an object and returns true if it is a Vinyl file, otherwise returns false.
Note: This method uses an internal flag that some older versions of Vinyl didn't expose.
Example:
var Vinyl = require('vinyl');
var file = new Vinyl();
var notAFile = {};
Vinyl.isVinyl(file); // true
Vinyl.isVinyl(notAFile); // false
Vinyl.isCustomProp(property)Static method used by Vinyl when setting values inside the constructor or when copying properties in file.clone().
Takes a string property and returns true if the property is not used internally, otherwise returns false.
This method is useful for inheritting from the Vinyl constructor. Read more in Extending Vinyl.
Example:
var Vinyl = require('vinyl');
Vinyl.isCustomProp('sourceMap'); // true
Vinyl.isCustomProp('path'); // false -> internal getter/setter
Since all properties are normalized in their setters, you can just concatenate with /, and normalization takes care of it properly on all platforms.
Example:
var file = new File();
file.path = '/' + 'test' + '/' + 'foo.bar';
console.log(file.path);
// posix => /test/foo.bar
// win32 => \\test\\foo.bar
But never concatenate with \, since that is a valid filename character on posix system.
When extending Vinyl into your own class with extra features, you need to think about a few things.
When you have your own properties that are managed internally, you need to extend the static isCustomProp method to return false when one of these properties is queried.
var Vinyl = require('vinyl');
var builtInProps = ['foo', '_foo'];
class SuperFile extends Vinyl {
constructor(options) {
super(options);
this._foo = 'example internal read-only value';
}
get foo() {
return this._foo;
}
static isCustomProp(name) {
return super.isCustomProp(name) && builtInProps.indexOf(name) === -1;
}
}
// `foo` won't be assigned to the object below
new SuperFile({ foo: "something" });
This makes properties foo and _foo skipped when passed in options to constructor(options) so they don't get assigned to the new object and override your custom implementation. They also won't be copied when cloning. Note: The _foo and foo properties will still exist on the created/cloned object because you are assigning _foo in the constructor and foo is defined on the prototype.
Same goes for clone(). If you have your own internal stuff that needs special handling during cloning, you should extend it to do so.
MIT
3.0.0 (2022-09-26)
inspect method & rely on util.inspect.custom symbolFAQs
Virtual file format.
We found that vinyl demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.